home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 201-220 / scopedisk211 / amenu / amenu.doc < prev    next >
Encoding:
Text File  |  1995-03-20  |  18.0 KB  |  408 lines

  1.  
  2.  
  3.                AMenu v1.3 (Anthony's Menu) Documentation
  4.  
  5.  
  6.       AMenu is a complete reprogramed version of Darin Johnson's
  7.   `MyMenu v1.0' from `Fish Disk 225'.  Its purpose is to attach extra
  8.   menus to the workbench menus and execute commands when selected.
  9.  
  10.      The original program `MyMenu' had a number of problems. Commands
  11.   run in the CLI always had a current directory of the boot device and
  12.   failed if no disk is present in that device. Also the stack size for
  13.   the commands was fixed to 4000 bytes, too small for many such
  14.   commands. Further more, if any program changes the Preferances of
  15.   the workbench (Programs such as Preferences, AudioMaster, and many
  16.   WordProcesses), the extra menus will be disconnected and need to be
  17.   reattached by manually restarting MyMenu to continue their use. Also
  18.   MyMenu required the Tool of a Project that was run in WB mode to
  19.   have an attached icon.
  20.  
  21.      AMenu solves all these problems. The default current directory
  22.   for CLI type commands is now selectable and defaults to the assigned
  23.   `SYS:' directory rather than the boot device. Commands can also have
  24.   their current directory, run prioity and stack size individually
  25.   set. Commands can also be run with a console which will accept input
  26.   as well as ouput to/from the command.
  27.      Titles or comment items can also be added to the menus, and more
  28.   style and coloring options are available and spacing between menus
  29.   can also be adjusted to the users desire.
  30.      The format for AMenu's script file is greatly different to that
  31.   of MyMenu.  Instead a structured format is used simular to another
  32.   MyMenu derivative, `ParM' (Fish Disk 375). This format allows the
  33.   addition of columned menus to AMenu and the ability to modify the
  34.   style of a sub-menu after the head item of the sub-menu is given.
  35.      AMenu performes more extensive error checking than MyMenu in both
  36.   the reading of the configuration file and in the command execution
  37.   making it easier on the user to debug his menus. MyMenu often just
  38.   does nothing on an error, leaving the user in the dark.
  39.      To top all this off, the size of the AMenu-Handler (the resident
  40.   controlling program) is smaller than that of the MyMenu-Handler!
  41.   ( AMenu-Handler - 4780 bytes   vs.  MyMenu-Handler - 5412 bytes )
  42.  
  43.      I renamed MyMenu to AMenu so as to avoid any confusion in thier
  44.   config files which are incompatable and to differentate my version
  45.   from any future releases he may care to make. (Apology to Darin)
  46.  
  47.  
  48. Installation:
  49.  
  50.      NOTE: The "ARP.Library" (version 35 or greater) must be installed
  51.   in the "L:" directory.   AMenu does not directly require the "Run"
  52.   command in "C:" as did MyMenu.
  53.  
  54.      Copy "AMenu-Handler" to the "L:" directory.  AMenu will also look
  55.   for this file in the current directory if it does not exist in the
  56.   "L:" directory.
  57.  
  58.      Simularity the file "AMenu.Config" should be in the "S:". If not
  59.   present, AMenu will also look in the current directory.
  60.  
  61.      If you already have a "MyMenu.Conf" in your "S:" directory,
  62.   rename it "AMenu.Config", and then edit it to convert any `CLI'
  63.   command execution mode to the AMenu's equivelent mode `RB'
  64.   (RunBack). After that it is a matter of grouping items in the same
  65.   menu together and changing the structure to the format given in the
  66.   sample config file, and this manual.
  67.  
  68.  
  69. Running:
  70.  
  71.   Syntax :
  72.       AMenu [quit]
  73.  
  74.      The command "AMenu" will load and start up the handler process.
  75.   Or if already running, it will re-parse the configuration file.
  76.  
  77.      The quit argument will remove AMenu, and has been throughly
  78.   checked for memory leaks.  MyMenu does have a leak of about 40
  79.   bytes. ASIDE: It seems almost all Manx pograms have this leak.
  80.  
  81.  
  82. Configuration file:
  83.  
  84.      "AMenu.Config" is stored in the "S:" directory but is also looked
  85.   for in the current directory.
  86.  
  87.      If any names used in the config file contain white space or non
  88.   alpha-numeric characters they should be quoted, a single word name
  89.   however does not need quotes.
  90.  
  91.    Example:
  92.       "SubMenu ->"
  93.  
  94.      A Comment can appear almost anywhere in the command file. The
  95.   only axception is after the name of a command to execute is given in
  96.   an ITEM statement. In this case the comment would be thought to be
  97.   part of the arguments to the command itself and executed when the
  98.   command is executed. A comment is prefaced with a `#' character and
  99.   then everything from there, up to and including the end of line.
  100.  
  101.   Example:
  102.       # This is a comment is ignored by AMenu as a Comment!
  103.  
  104.  
  105.   COLOR  fore back  - Text Color   ( default is black on white  ( 2 1 ) )
  106.   TCOLOR fore back  - Title Color  ( default is black on orange ( 2 3 ) )
  107.  
  108.        These statements define the colors to use in the creation of
  109.     the MenuItems that follow. COLOR is used for command items while
  110.     TCOLOR is the coloring of menu titles (Menu Comments).
  111.        Note:- The Menus use the same general background color as
  112.     workbench and thus the default colors for TITLE's is really, black
  113.     text on orange background on a white menu.
  114.  
  115.  
  116.   STYLE COMP     - highlight menu items by inverting colors (Default)
  117.   STYLE BOX      - highlight by drawing a box around them.
  118.  
  119.        Select the style to use in highlighting menu items that follow.
  120.     After the STYLE statement either BOX or COMP must be given. This
  121.     is only used for command items and sub-menu names. Menu titles
  122.     contain no highlighting as they perform no action when selected.
  123.  
  124.  
  125.   MENUGAP n   - Gap between menus  (default as per workbench menus )
  126.  
  127.        This command defines the amount of space (in characters) to add
  128.     when creating a new menu. The value is only used when a new menu
  129.     name is given in the MENU command intailing the creation of
  130.     another menu.
  131.        To have the menus as close togetter as possible use a value of
  132.     1. If the value is too big, menus may overflow the screen which
  133.     AMenu will warn you about but will continue regardless.
  134.  
  135.  
  136.   DIRECTORY full-dir-path       ( Default "Sys:" )
  137.  
  138.        This statement defines the default current directory to use to
  139.     find and execute commands. If this command is not given the
  140.     current directory defaults to the assigned "Sys:" directory (Not
  141.     the Boot device (DF0:) as MyMenu does). It should be defined only
  142.     once in a file and if multiply defined only the last will be used.
  143.     The DIR command-modifier works from this directory path, so you
  144.     need not give a full pathname to individual commands (using less
  145.     memory to store).
  146.  
  147.  
  148.   CONSOLE console-name     ( Default "CON:100/11/200/20/AMenu Command" )
  149.  
  150.        This sets the name of the console to use for commands with the
  151.     execution-mode CLI. This can be changed on an individual basis using
  152.     the CON command modifier. As with DIRECTORY only one of these should be
  153.     given if at all. If more than one is fould only the last will be used.
  154.  
  155.  
  156.   MENU [COLUMNS n] menu-name
  157.   ENDMENU
  158.   SUBMENU [COLUMNS n] submenu-name
  159.   ENDSUBMENU
  160.  
  161.        These statements define the overall menu structure. The COLUMNS
  162.     option is a new feature which allows the user to define the number of
  163.     columns the menu is to spread its element over. If COLUMNS is not given
  164.     it defaults to the normal value of one column. Items in a menu are
  165.     arranged in column order as showen in the figure below.
  166.        A SUBMENU command must occur within a MENU structure and under
  167.     the current scheme of intuition, you are not allowed a
  168.     "SUBSUBMENU" within a SUBMENU.
  169.        The ENDMENU statement is actually not needed as another MENU
  170.     statement (or end of file) following implys the end of the previous
  171.     menu. The same is true for ENDSUBMENU but is required if more items
  172.     follow in the surrounding MENU structure (as in the figure below).
  173.       _________________________________________________________
  174.       ________|_Menu_|_________________________________________
  175.               |  Title    Item 5   |
  176.               |  Item 1   Item 6  _|___________________
  177.               |  Item 2   SubMenu| Sub 1  Sub 3  Sub 4 |
  178.               |  Item 3   Item 7 |_Sub_2_________Sub_5_|
  179.               |__Item_4____________|        ^.
  180.                                               Space left by SKIP!
  181.       Figure: a 2 column menu with 3 column sub-menu.
  182.  
  183.  
  184.   TITLE title-name
  185.   SKIP
  186.   ITEM  item-name [<char>] | exec-mode [modifiers] command command-args
  187.  
  188.        These three elements and any SubMenu names form the contents of
  189.     any particular menu.  They are added to the current menu in the
  190.     order given in columns. The number of elements stored in each
  191.     column is decided by AMenu by dividing the number of elements
  192.     given in a particular menu by the number of columns that menu has
  193.     and can be adjusted using SKIP statements. (See SKIP below).
  194.  
  195.        The TITLE element defines an menu item which is a comment.
  196.     Selecting this item does nothing. In fact it will not even
  197.     highlight when the mouse is over it. A collection of these could
  198.     be used to make a type of menu note about something.  The coloring
  199.     for this element is defined with the TCOLOR statement and is often
  200.     used to make a title standout from the normal ITEM's. They are
  201.     most commonly used at the top of the first column but can appear
  202.     anywhere.
  203.  
  204.        SKIP is used to leave gaps in the menu structure, or to insure
  205.     AMenu correctly arranges the elements in the appropiate columns.
  206.     It up no memory as it doesn't add any new menu elements to the
  207.     menu. IE no cost. WARNING: Skip'ed space on the edge or bottom of
  208.     a menu may be removed automatically by the intuition menu display
  209.     routines and thus ignored in the final display of the menu.  If
  210.     you really want the space on the edge of the menu use a TITLE
  211.     element with TColor set to 1 1 (white text on a white background
  212.     on a white menu) to make it invisible.
  213.  
  214.        ITEM define the actual job of AMenu. When such a element is
  215.     selected the command given is run in background using one of three
  216.     styles of execution.
  217.        The optional <char> is used as a menu key shortcut by pressing
  218.     the Right-Amiga key and that letter. It must be surrounded by <>'s
  219.     if given.  NOTE: This also adds a Amiga-letter symbol to the
  220.     displayed menu element.
  221.  
  222.        The vertical bar `|' is used to seperate the menu definition
  223.     from the command definition. Following this is one of three
  224.     exec-modes notifing AMenu the method in with the command is to be
  225.     run.
  226.  
  227.         RB or RUNBACK
  228.                 - the command is executed in "RunBack" or "ARun NOIO"
  229.                   style. This is equivelent (but not same as) the CLI
  230.                   command execution mode used in MyMenu. No console is
  231.                   provided and any output will be lost.
  232.  
  233.         CLI     - a console is opened for the command to output to or
  234.                   recieve input from. The console will automatically
  235.                   close on the command exit. and can be defined using
  236.                   the CONSOLE command globally or using the CON
  237.                   modifer locally (See below).          (New to AMenu)
  238.  
  239.         SCR or SCRIPT
  240.                 - This is equivelent to the command `NewCLI' or
  241.                   `AShell'. This starts a new shell window, with the
  242.                   command given being used as a `FROM' script file. If
  243.                   the script does not end in a `EndCLI' command the
  244.                   console will then become an interactive shell
  245.                   window. A good script to use is "S:Shell-Startup"
  246.                   which will start a normal shell window.
  247.  
  248.         WB      - The command is run as if started from the Workbench
  249.                   As from AMenu v1.3 this command has been fixed so
  250.                   that it works correctly for projects (as if just the
  251.                   project was double-clicked) as well as tools. It
  252.                   does this in a way that also avoids a bug in the
  253.                   lattice C startup code (See WBTests.txt).
  254.  
  255.  
  256.       The following modifiers allow the user to change the way the
  257.    environment is set up when this command is executed. Zero or more
  258.    the following can be used :-
  259.  
  260.         PRI prioity-number         ( All modes )
  261.                   Sets the prioity to somthing other 0 the default
  262.                   prioity.  Eg: -20 will run only if nothing else
  263.                   does. This is to be used with caution as a bad
  264.                   prioity could cause problems on the system. I
  265.                   suggest you only use the range -20 to 5.
  266.  
  267.         STK stack-size             ( All Modes )
  268.                   This uses a different stack size for the command
  269.                   other than the default size of 4096. For WB mode the
  270.                   stack is set to this ONLY if the stack setting in
  271.                   the icon executed is less than this or non-existant.
  272.                   IE: the larger of the two is used for the tool.
  273.  
  274.         DIR dir-path               ( Any Mode but WB )
  275.                   Use this dir-path as the current directory for the
  276.                   command. This path is from the default directory
  277.                   given with the DIRECTORY command above. The current
  278.                   directory for WB programs is that of the tool
  279.                   executed.
  280.  
  281.         CON console-name           ( CLI and SCR modes only )
  282.                   Use a different console window, for this particular
  283.                   command or script than that set with the CONSOLE
  284.                   command above.
  285.  
  286.        After these options the command name wust be given. After the
  287.     command is given the rest of the line is treated as arguments to
  288.     that command. NOTE:- WB and SCR modes ignores these arguments
  289.     completely.
  290.  
  291.  
  292.   Examples:
  293.  
  294.     Item "JrComm" | WB  Sys:Tools/Comms/JrComm
  295.  
  296.        Executes the command "JrComm", stored in the directory
  297.     "Sys:Tools/Comms", using the current defaults, and executed as if
  298.     started by workbench.
  299.  
  300.     SubMenu "AMenu ->"
  301.       Title " AMenu "
  302.       Item  "Rebuild" | RB Dir Utilities AMenu
  303.       Item  " QUIT  " | RB Dir Utilities AMenu quit
  304.     EndSubMenu
  305.  
  306.        Defines a sub-menu with a title to execute the command "AMenu"
  307.     stored in the directory "Utilities" off the default directory
  308.     (probably SYS: is not set) with different arguments.
  309.        NOTE: This is segested way to execute AMenu from itself. It
  310.     assumes that the "AMenu.Config" file is stored either in the "S:"
  311.     directory where it should be or in the "Utilities" directory (the
  312.     current directory for command).
  313.  
  314.  
  315. Other Notes on Config:
  316.  
  317.      The case of all Statements words used in AMenu is ignored. While
  318.   the case for names is recored literally.
  319.  
  320.      Line breaks can occur at any time in any statement and is treated
  321.   as normal white space. The ITEM command is no different in this
  322.   respect until the command name is given. After the command name, ALL
  323.   TEXT until the end of line is treated as the commands argument and
  324.   as such can't be broken by newline characters, nor should it contain
  325.   a comment.
  326.  
  327.     Line Breaks are ok in the following :
  328.        ITEM Archologist
  329.           | RB  DIR NetHack:
  330.                 STK 8000
  331.                 NetHack -A -u Archie
  332.  
  333.     Illegal Line break in this menu command :
  334.        ITEM Archologist | RB DIR NetHack:  Stk 8000  NetHack -A
  335.                   -u Archie
  336.  
  337.      AMenu uses the "AmigaDOS Replacment Project" or ARP Library. In
  338.   particular it uses "ASynchRun()" function rather than the AmigaDOS
  339.   "Execute()" to execute CLI and RB commands. This function will NOT
  340.   execute scripts directly (reporting an error to that effect). To
  341.   execute a script use the following method. Note however that the
  342.   script should end in "EndCLI" to close the window.
  343.  
  344.       ITEM ExecuteScript | RB  NewCLI con: FROM script-file
  345.  
  346.  
  347. Re-Compiling:
  348.  
  349.      Version 1.1 of AMenu (unreleased) was a complete reprogram of
  350.   MyMenu v1.0. I added all the new commands above but retained the
  351.   orignal single "MENU" statement for all menu elements.
  352.  
  353.      AMenu v1.2 only reprogramed the files "Parse.c" and "Menu.c" to
  354.   add structuring statements and remove the named searches of menus
  355.   already created. This simplified "Menu.c" and allowed the addition
  356.   of columns, recursive menu positioning, and the ability to change
  357.   menu style between the declaration of a SubMenu and the first
  358.   element in the submenu.
  359.  
  360.      For "AMenu-Handler", I use a C startup file "_main.c" rather than
  361.   "lib:c.o". I did this as AMenu-Handler is a Process, but, must not
  362.   wait for a nonexistant WBStartup message. Also "lib:c.o" is very
  363.   large, 1136 bytes, while "_main.o" is only 164 bytes. A considerable
  364.   difference in size (and memory usage).
  365.  
  366.      Version 1.3 is a rewrite of the Workbench startup code to stop some
  367.   annoying bugs and the addition of my "ArpC" Arp library startup code.
  368.  
  369.  
  370. Limitations, bugs, and other wierd things:
  371.  
  372.      The search path for commands is only the current dir (set with
  373.   DIR or the default DIRECTORY) and the "C:" directory. I do not
  374.   at this time intend expanding this path. Though I do know how to
  375.   do so.
  376.  
  377.  
  378. Acknowledgements:
  379.  
  380.   by Darin Johnson
  381.     Matt Dillon     - Ideas for menu building and how to load in the
  382.                        handler were taken from DME and DMouse.
  383.     Peter da Silva  - Ideas taken from wblaunch program.
  384.     Rob Peck        - Some ideas and help.
  385.     Davide Cervone  - LOTS of ideas taken from MonIDCMP.
  386.  
  387.   by Anthony Thyssen
  388.     Darin Johnson   - for MyMenu the best command menu program (until now)
  389.     Doug Walker     - C startup methond used in "_main.c" for AMenu-Handler
  390.                        and ArpC startup code for ARP programs.
  391.     ARP Team        - for ARP, Prog. Guild, and ARun as an example
  392.     Sylvain Rougier & Pierre Carrette
  393.                     - auther of ParM for structured menu style
  394.       NOTE:- Much of the code from ParM v1.3 was taken from MyMenu but these
  395.     pirates (no offence) make no mention of this fact, thus claiming it
  396.     is all their own work. They should have done so. (In a latter release
  397.     of ParM SR & PC did make small mention in their programs history)
  398.  
  399.  
  400. Signature:
  401.  
  402.       Anthony Thyssen (Dragon Computing),
  403.                co/  Commodore Computer Users Group (Qld) Inc.
  404.                     P.O. Box 274, Springwood, Qld., Australia, 4127
  405.  
  406.     Beware, The light at the end of the tunnel may be a oncoming dragon!
  407.  
  408.